Contents
ApiMon Help Contents

Introduction

What Is ApiMon?

How To Use ApiMon

Usage

Command Line Options

Options

Miscellaneous Options

Enable Tracing

Enable Counters

Pre-Load Symbols

Disable Heap Checking

Go Immediately

Don’t Use Fast Counters

Monitor Known DLLs Only

Monitor Page Faults

Default Counter Sorting

File Names Options

Log File Name

Trace File Name

Symbol Path

Known DLLs Options


What Is ApiMon?
ApiMon

What Is ApiMon?

ApiMon monitors a running application for application programming interface (API) calls.  ApiMon counts and times all API calls.  It can also, optionally, monitor page faults caused by the monitored application and report them by API call.

You can use ApiMon as a performance monitor to help tune your application.  The data can be used to determine where the hot spots are in your application, by examining the APIs with the largest times and/or counts.  You can also look at which APIs are used by the application, taking a special look at calls that cause ring transitions to kernel mode or client/server transitions.  Ring (or kernel-mode) transitions occur when user-mode processes use APIs to switch their threads from user to kernel mode.  Large numbers of these calls can be culprits for the cause of a slow application.

ApiMon can generate two types of reports: a report containing all API calls showing their counts and times, and a report showing a trace of all APIs as they occurred in time.


How To Use ApiMon
ApiMon

How To Use ApiMon

You can launch ApiMon either from the command prompt, Run on the Start menu, or Windows Explorer.  After ApiMon starts, you must open a program for monitoring. You can optionally specify the program name as an command-line argument to ApiMon.

After a program is opened, you can start monitoring it by pushing the Go traffic light or selecting the Start Monitor menu item under the Tools menu.  When the application starts, two windows appear.  The first window is the API counter and timer and the second is the current dynamic link library (DLL) list window.


Command-Line Options
ApiMon

Command-Line Options

The command line syntax for ApiMon is as follows:

apimon [-g] [appname]

Where:

-g

starts the application immediately.

appname

is the name of the application to be monitored.


Miscellaneous Options
ApiMon

Miscellaneous Options

Use this property page to set the options that control the behavior of ApiMon.

To get help on an option, click the text of the option.


Enable Tracing
ApiMon

Miscellaneous Options
Enable Tracing

Turns on API tracing.  This causes ApiMon to create a trace file containing one line of text for each API call made by the monitored application.  The trace contains the following information:

1. Return address

2. First four arguments

3. API name


Enable Counters
ApiMon

Miscellaneous Options
Enable Counters

Turns on API counting and timing.


Pre-Load Symbols
ApiMon

Miscellaneous Options
Pre-Load Symbols

Enabling this option causes ApiMon to load the debug symbols for all dynamic link libraries (DLLs)  while the monitored program is running.  This option is turned on when Monitor Page Faults is turned on.


Disable Heap Checking
ApiMon

Miscellaneous Options
Disable Heap Checking

When a process is being debugged, NTDLL’s heap manager turns on a set of heap-checking flags.  This ensures that if the process corrupts its heap, the debugger will catch the error.  This behavior also slows down the process and changes the characteristics of the heap.  The Disable Help Checking  options disables this behavior and allows the process to run as if it were not being debugged.


Go Immediately
ApiMon

Miscellaneous Options
Go Immediately

This option causes ApiMon to start the monitor for the application as soon as the program is opened through the File | Open menu selection or when a program name is specified on the ApiMon command line.


Don't Use Fast Counters
ApiMon

Miscellaneous Options
Don’t Use Fast Counters

On the Intel Pentium processor, ApiMon can use special instructions to do the API timings.  The other processors must use the Win32 API called GetPerformanceCounter().  This option disables the use of these instructions if ApiMon is running on one of the supported platforms.


Monitor Known DLLs Only
ApiMon

Miscellaneous Options
Monitor Known DLLs Only

By default ApiMon monitors API calls to all dynamic link libraries (DLLs) that the monitored process loads, either statically or dynamically.  This option provides for the monitoring of a specific list of DLLs to be monitored.  To create the DLL list see the Known DLLs Options.


Monitor Page Faults
ApiMon

Miscellaneous Options
Monitor Page Faults

Enabling this option causes ApiMon to create a new window that displays page fault information.  The window displays one entry for each API from all enabled dynamic link libraries (DLLs) that has caused a page fault.


Default Counter Sorting
ApiMon

Miscellaneous Options
Default Counter Sorting

This option specifies the default sort order for the API counter window.  The sort order can be changed while the monitor is running.


File Names Options
ApiMon

File Names Options

To get help on a file name, click the text of the file name.


Log File Name
ApiMon

File Names Options
Log File Name

Specify a full path and file name for the ApiMon log file.  You may specify a file on your local computer or a UNC name (share) to a network path and name.  This file is created when the menu command File | Write Data To Log File is selected.  The file is overwritten each time the log file is created.


Trace File Name
ApiMon

File Names Options
Trace File Name

Specify a full path and file name for the Trace file.  You may specify a file on your local computer or a UNC (share) name to a network path and name.  This file is created when the Enable Tracing  option is turned on.  The file is overwritten each time the trace file is created.


Symbol Path
ApiMon

File Names Options
Symbol Path

This string is a path or multiple paths separated by semicolons.  Each path points to a tree containing debug symbols.  The debug symbols can be either .dbg files, .exe files, or .pdb files.  This string is necessary if the Pre-Load Symbols option is turned on.


Known DLLs Options
ApiMon

Known DLLs Options

This property page is used to specify a list of known dynamic link libraries (DLLs) that are initially monitored by ApiMon.  This is useful if you don’t want ApiMon to clutter the display and log file with statistics that you don’t care about.

To add a new entry to the list, click an empty entry and an edit box appears.  Enter the DLL name and press enter.  The DLL name must not contain a full path, just the file name with a .dll extension.

To delete an entry, click the desired entry, delete all of the text, and press enter.  The entry is then removed from the list.

In order for this DLL list to take effect, the Monitor Known DLLs Only option must be turned on.